Description

The EVM paywall hardcodes / 1000000 everywhere, breaking display amounts for any token that isn't a 6-decimal stablecoin. An 18-decimal token priced at 0.001 raw units renders as $1,000,000,000. The assumption appears in three places — server-side HTML generation, client-side balance display, and a USDC-only address lookup table.

Closes #1979.

Approach

The PR replaces the hardcoded-6-decimal assumption on both sides of the paywall:

Server side (@x402/paywall/src/evm/index.ts)

• Replace the hardcoded / 1000000 divisor with a lookup against @x402/evm's DEFAULT_STABLECOINS registry, with a fallback to 6 (USDC default) when the network isn't in the registry.
• Replace the lossy parseFloat(amount) / 10**decimals math with Number(formatUnits(BigInt(amount), decimals)) so atomic-to-display conversion preserves precision through 18-decimal amounts. BigInt also rejects non-integer atomic strings, which matches the spec's atomic-integer contract.

Client side (@x402/paywall/src/evm/EvmPaywall.tsx)

• Read the token contract address from the payment requirement's asset field (server populates it).
• Query the standard ERC-20 decimals() function on-chain via the new getTokenDecimals helper in utils.ts, so balance formatting uses the actual token's precision.
• State variable renamed formattedUsdcBalance → formattedBalance; balance-check callback renamed checkUSDCBalance → checkBalance.

Internal utility (@x402/paywall/src/evm/utils.ts)

• Replace the internal getUSDCBalance(client, address) — which hardcoded USDC contract addresses for three chains (Ethereum, Base, Base Sepolia) and returned 0n for every other chain — with generic:
  • getTokenBalance(client, owner, tokenAddress) — ERC-20 balanceOf against the supplied token address
  • getTokenDecimals(client, tokenAddress) — ERC-20 decimals() against the supplied token address, with a 6 fallback on error
• Drops the USDC_ADDRESSES map entirely.
• Breaking change (internal): getUSDCBalance is removed. This helper was not part of the package's public API (exports map); it was only consumed by the bundled EvmPaywall React component inside the paywall HTML template. No server-operator code path calls it. Anyone who has forked the paywall and imports from the internal file path (bypassing package exports) would need to update their import and call site.

@x402/evm public API

@x402/evm now publicly re-exports DEFAULT_STABLECOINS from ./shared/defaultAssets so consumers can read the canonical default-asset registry directly.

Generated templates

The baked EVM paywall bundles (typescript/packages/http/paywall/src/evm/gen/template.ts, go/http/evm_paywall_template.go, python/x402/http/paywall/evm_paywall_template.py) are regenerated to carry the updated EvmPaywall.tsx / utils.ts. SVM templates are regenerated for toolchain parity — the build step emits both.

Why this approach

@x402/evm's DEFAULT_STABLECOINS registry already holds the decimals field for every supported chain (eip155:31611 / Mezo mUSD = 18, eip155:4326 / MegaETH MegaUSD = 18, every other chain's default = 6). The same registry powers existing dispatch paths in the SDK:

• scheme.getAssetDecimals(asset, network) on both the exact and upto EVM schemes
• The inline scheme?.getAssetDecimals?.(...) dispatch in @x402/core's x402ResourceServer (server.ts:795)

The paywall now consolidates the registry lookup so all consumers share the same source within a published version, rather than carrying a parallel map. A new chain added to DEFAULT_STABLECOINS is picked up by the paywall when the consumer upgrades @x402/evm — no paywall rebuild required.

@x402/paywall already imports from @x402/evm for client-side code; this PR extends that to the server-side decimals lookup.

Tests

pnpm --filter @x402/paywall test --run network-handlers — 12/12 pass (6 new tests added):

• getDefaultTokenDecimals returns 18 for Mezo Testnet (eip155:31611)
• getDefaultTokenDecimals returns 6 for Base mainnet (eip155:8453), with DEFAULT_STABLECOINS["eip155:8453"] asserted alongside so an empty registry would fail the test
• getDefaultTokenDecimals falls back to 6 for networks not in the registry
• evmPaywall.generateHtml end-to-end on a Mezo Testnet 18-decimal payment: 1000000000000000 atomic renders as amount: 0.001, in the inline window.x402 script (the regression test for the / 1e6 order-of-magnitude bug)
• evmPaywall.generateHtml end-to-end on a Base mainnet 6-decimal payment: 1000000 atomic renders as amount: 1,
• evmPaywall.generateHtml throws on a non-integer atomic amount string ("1.5"), pinning the BigInt strictness so a future revert to parseFloat would fail